/*!
 * \file locking_ptr.hpp
 * \brief 带作用域锁定机制的智能指针
 *
 * \details locking_ptr是一个具有作用域锁定机制的智能指针。
 *          
 *          这个类是volatile指针的包装器，通过锁定传入的互斥锁，
 *          实现对内部指针的同步访问。
 *          
 *          核心特性：
 *          - RAII锁管理：构造时自动加锁，析构时自动解锁
 *          - volatile语义支持：处理多线程环境下的可见性问题
 *          - 简化的同步访问：提供类似普通指针的使用方式
 *          - 异常安全：确保即使发生异常也能正确解锁
 *          
 *          设计基础：
 *          locking_ptr基于Andrei Alexandrescu的LockingPtr设计。
 *          更多信息参见A. Alexandrescu的文章
 *          "volatile - Multithreaded Programmer's Best Friend"。
 *          
 *          典型用法：
 *          \\code
 *          volatile MyClass obj;
 *          mutex mtx;
 *          {
 *              locking_ptr<MyClass, mutex> ptr(obj, mtx);
 *              ptr->method();  // 自动同步访问
 *          } // 作用域结束时自动解锁
 *          \\endcode
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */


#ifndef THREADPOOL_DETAIL_LOCKING_PTR_HPP_INCLUDED
#define THREADPOOL_DETAIL_LOCKING_PTR_HPP_INCLUDED

#include <boost/utility.hpp>
#include <boost/thread/mutex.hpp>


namespace boost { namespace threadpool { namespace detail 
{

/*!
 * \brief 带作用域锁定机制的智能指针
 *
 * \details 这个类是volatile指针的包装器，通过锁定传入的互斥锁
 *          实现对内部指针的同步访问。
 *          
 *          主要特点：
 *          - 自动锁管理：构造时加锁，析构时解锁
 *          - 异常安全：即使发生异常也保证正确解锁
 *          - 透明访问：提供operator*和operator->
 *          - 不可复制：防止意外的锁复制
 *          
 *          使用场景：
 *          - 需要对volatile对象进行同步访问
 *          - 要求简化的锁管理语义
 *          - 需要异常安全的同步机制
 *
 * \tparam T 被管理对象的类型
 * \tparam Mutex 互斥锁的类型
 */
  template <typename T, typename Mutex>
  class locking_ptr 
  : private noncopyable
  {
    T* m_obj;                     //!< 实例指针
    Mutex & m_mutex;              //!< 用于作用域锁定的互斥锁引用

  public:
    /*!
     * \brief 构造函数
     * \param obj 要管理的volatile对象引用
     * \param mtx 用于同步的volatile互斥锁引用
     * 
     * \details 构造locking_ptr时自动锁定互斥锁，确保在对象
     *          生命周期内对目标对象的独占访问。
     *          
     *          const_cast的使用：
     *          由于需要操作volatile对象，使用const_cast移除
     *          volatile和const限定符以便正常操作。这是安全的，
     *          因为锁定机制保证了同步访问。
     */
    locking_ptr(volatile T& obj, const volatile Mutex& mtx)
      : m_obj(const_cast<T*>(&obj))
      , m_mutex(*const_cast<Mutex*>(&mtx))
    {   
      // 锁定互斥锁
	  m_mutex.lock();
    }

    /*!
     * \brief 析构函数
     * 
     * \details 析构时自动解锁互斥锁，实现RAII语义。
     *          即使在异常情况下，也能保证锁被正确释放。
     */
    ~locking_ptr()
    { 
      // 解锁互斥锁
      m_mutex.unlock();
    }

    /*!
     * \brief 解引用操作符
     * \return 存储实例的引用
     * 
     * \details 提供对被管理对象的引用访问。由于构造时已经
     *          加锁，此访问是线程安全的。
     */
    T& operator*() const
    {    
      return *m_obj;    
    }

    /*!
     * \brief 成员访问操作符
     * \return 存储实例的指针
     * 
     * \details 提供对被管理对象成员的指针访问。由于构造时
     *          已经加锁，此访问是线程安全的。
     */
    T* operator->() const
    {   
      return m_obj;   
    }
  };


} } } // namespace boost::threadpool::detail


#endif // THREADPOOL_DETAIL_LOCKING_PTR_HPP_INCLUDED

